---
sidebar_position: 3.2
id: "secrets"
title: "Secrets"
---

import { VersionBadge } from "@site/src/components/versionbadge";

# Secrets

<VersionBadge version="v0.13" />

Wave Terminal provides a secure way to store sensitive information like passwords, API keys, and tokens. Secrets are stored encrypted in your system's native keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service), ensuring your sensitive data remains protected.

## Why Use Secrets?

Secrets in Wave Terminal allow you to:

- **Store SSH passwords** - Automatically authenticate to SSH connections without typing passwords
- **Manage API keys** - Keep API tokens, keys, and credentials secure
- **Share across sessions** - Access your secrets from any terminal block or remote connection
- **Avoid plaintext storage** - Never store sensitive data in configuration files or scripts

## Opening the Secrets UI

There are several ways to access the secrets management interface:

1. **From the widgets bar** (recommended):
   - Click the **<i className="fa-gear fa-solid fa-sharp"/>** settings icon on the widgets bar
   - Select **Secrets** from the menu

2. **From the command line:**
   ```bash
   wsh secret ui
   ```


The secrets UI provides a visual interface to view, add, edit, and delete secrets.

## Managing Secrets via CLI

Wave Terminal provides a complete CLI for managing secrets from any terminal block:

```bash
# List all secret names (not values)
wsh secret list

# Get a specific secret value
wsh secret get MY_SECRET_NAME

# Set a secret (format: name=value, no spaces around =)
wsh secret set GITHUB_TOKEN=ghp_xxxxxxxxxx
wsh secret set DB_PASSWORD=super_secure_password

# Delete a secret
wsh secret delete MY_SECRET_NAME
```

## Secret Naming Rules

Secret names must match the pattern: `^[A-Za-z][A-Za-z0-9_]*$`

This means:
- Must start with a letter (A-Z or a-z)
- Can only contain letters, numbers, and underscores
- Cannot contain spaces or special characters

**Valid names:** `MY_SECRET`, `ApiKey`, `ssh_password_1`
**Invalid names:** `123_SECRET`, `my-secret`, `secret name`

## Using Secrets with SSH Connections

<VersionBadge version="v0.13" />

Secrets can be used to automatically provide passwords for SSH connections, eliminating the need to type passwords repeatedly.

### Configure in connections.json

Add the `ssh:passwordsecretname` field to your connection configuration:

```json
{
    "myserver": {
        "ssh:hostname": "example.com",
        "ssh:user": "myuser",
        "ssh:passwordsecretname": "SERVER_PASSWORD"
    }
}
```

Then store your password as a secret:

```bash
wsh secret set SERVER_PASSWORD=my_actual_password
```

Now when Wave connects to `myserver`, it will automatically use the password from your secret store instead of prompting you.

### Benefits

- **Security**: Password stored encrypted in your system keychain
- **Convenience**: No need to type passwords for each connection
- **Flexibility**: Update passwords by changing the secret, not the configuration

## Security Considerations

- **Encrypted Storage**: Secrets are stored encrypted in your Wave configuration directory. The encryption key itself is protected by your operating system's secure credential storage (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

- **No Plaintext**: Secrets are never stored unencrypted in logs or accessible files.

- **Access Control**: Secrets are only accessible to Wave Terminal.


## Storage Backend

Wave Terminal automatically detects and uses the appropriate secret storage backend for your operating system:

- **macOS**: Uses the macOS Keychain
- **Windows**: Uses Windows Credential Manager
- **Linux**: Uses the Secret Service API (freedesktop.org specification)

:::warning Linux Secret Storage
On Linux systems, Wave requires a compatible secret service backend (typically GNOME Keyring or KWallet). These are usually pre-installed with your desktop environment. If no compatible backend is detected, you won't be able to set secrets, and the UI will display a warning.
:::

## Troubleshooting

### "No appropriate secret manager found"

This error occurs on Linux when no compatible secret service backend is available. Install GNOME Keyring or KWallet and ensure the secret service is running.

### Secret not found

Ensure the secret name is spelled correctly (names are case-sensitive) and that the secret exists:

```bash
wsh secret list
```

### Permission denied on Linux

The secret service may require you to unlock your keyring. This typically happens after login. Consult your desktop environment's documentation for keyring management.

## Related Documentation

- [Connections](/connections) - Learn about SSH connections and configuration
- [wsh Command Reference](/wsh-reference#secret) - Complete CLI command documentation for secrets